<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Creates a password hash</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="function.password-get-info.html">password_get_info</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="function.password-needs-rehash.html">password_needs_rehash</a></div>
 <div class="up"><a href="ref.password.html">Password Hashing 函数</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.password-hash" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">password_hash</h1>
  <p class="verinfo">(PHP 5 &gt;= 5.5.0)</p><p class="refpurpose"><span class="refname">password_hash</span> &mdash; <span class="dc-title">Creates a password hash</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-function.password-hash-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="type">string</span> <span class="methodname"><strong>password_hash</strong></span>
    ( <span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code></span>
   , <span class="methodparam"><span class="type">integer</span> <code class="parameter">$algo</code></span>
   [, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code></span>
  ] )</div>

  <p class="para rdfs-comment">
   <span class="function"><strong>password_hash()</strong></span> creates a new password hash using a strong one-way hashing
   algorithm. <span class="function"><strong>password_hash()</strong></span> is compatible with <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span>.
   Therefore, password hashes created by <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> can be used with
   <span class="function"><strong>password_hash()</strong></span>.
  </p>
  <p class="simpara">
   The following algorithms are currently supported:
  </p>
  <p class="para">
   <ul class="itemizedlist">
    <li class="listitem">
     <span class="simpara">
      <strong><code>PASSWORD_DEFAULT</code></strong> - Use the bcrypt algorithm (default as of PHP 5.5.0).
      Note that this constant is designed to change over time as new and stronger algorithms are added
      to PHP. For that reason, the length of the result from using this identifier can change over
      time. Therefore, it is recommended to store the result in a database column that can expand
      beyond 60 characters (255 characters would be a good choice).
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      <strong><code>PASSWORD_BCRYPT</code></strong> - Use the <strong><code>CRYPT_BLOWFISH</code></strong> algorithm to
      create the hash. This will produce a standard <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> compatible hash using
      the &quot;$2y$&quot; identifier. The result will always be a 60 character string,  或者在失败时返回 <strong><code>FALSE</code></strong>.
     </span>
     <p class="para">
      Supported Options:
     </p>
     <ul class="itemizedlist">
      <li class="listitem">
       <p class="para">
        <em>salt</em> - to manually provide a salt to use when hashing the password.
        Note that this will override and prevent a salt from being automatically generated.
       </p>
       <p class="para">
        If omitted, a random salt will be generated by <span class="function"><strong>password_hash()</strong></span> for
        each password hashed. This is the intended mode of operation.
       </p>
      </li>
      <li class="listitem">
       <p class="para">
        <em>cost</em> - which denotes the algorithmic cost that should be used. 
        Examples of these values can be found on the <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> page.
       </p>
       <p class="para">
        If omitted, a default value of <em>10</em> will be used. This is a good
        baseline cost, but you may want to consider increasing it depending on your hardware.
       </p>
      </li>
     </ul>
    </li>
   </ul>
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-function.password-hash-parameters">
  <h3 class="title">参数</h3>
  <dl>

   
    <dt>
<em><code class="parameter">password</code></em></dt>

    <dd>

     <p class="para">
      用户的密码。
     </p>
    </dd>

   
   
    <dt>
<em><code class="parameter">algo</code></em></dt>

    <dd>

     <p class="para">
      一个用来在散列密码时指示算法的<a href="password.constants.html" class="link">密码算法常量</a>。
     </p>
    </dd>

   
   
    <dt>
<em><code class="parameter">options</code></em></dt>

    <dd>

     <p class="para">
      一个包含有选项的关联数组。目前支持两个选项：<em>salt</em>，在散列密码时加的盐（干扰字符串），以及<em>cost</em>，用来指明算法递归的层数。这两个值的例子可在 <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> 页面找到。
     </p>
     <p class="para">
      If omitted, a random salt will be created and the default cost will be
      used.
     </p>
    </dd>

   
  </dl>

 </div>


 <div class="refsect1 returnvalues" id="refsect1-function.password-hash-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   Returns the hashed password,  或者在失败时返回 <strong><code>FALSE</code></strong>.
  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-function.password-hash-examples">
  <h3 class="title">范例</h3>
  <p class="para">
   <div class="example" id="example-846">
    <p><strong>Example #1 <span class="function"><strong>password_hash()</strong></span> example</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/**<br />&nbsp;*&nbsp;We&nbsp;just&nbsp;want&nbsp;to&nbsp;hash&nbsp;our&nbsp;password&nbsp;using&nbsp;the&nbsp;current&nbsp;DEFAULT&nbsp;algorithm.<br />&nbsp;*&nbsp;This&nbsp;is&nbsp;presently&nbsp;BCRYPT,&nbsp;and&nbsp;will&nbsp;produce&nbsp;a&nbsp;60&nbsp;character&nbsp;result.<br />&nbsp;*<br />&nbsp;*&nbsp;Beware&nbsp;that&nbsp;DEFAULT&nbsp;may&nbsp;change&nbsp;over&nbsp;time,&nbsp;so&nbsp;you&nbsp;would&nbsp;want&nbsp;to&nbsp;prepare<br />&nbsp;*&nbsp;By&nbsp;allowing&nbsp;your&nbsp;storage&nbsp;to&nbsp;expand&nbsp;past&nbsp;60&nbsp;characters&nbsp;(255&nbsp;would&nbsp;be&nbsp;good)<br />&nbsp;*/<br /></span><span style="color: #007700">echo&nbsp;</span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"rasmuslerdorf"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PASSWORD_DEFAULT</span><span style="color: #007700">).</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
</pre></div>
    </div>
   </div>
  </p> 
  <p class="para">
   <div class="example" id="example-847">
    <p><strong>Example #2 <span class="function"><strong>password_hash()</strong></span> example setting cost manually</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/**<br />&nbsp;*&nbsp;In&nbsp;this&nbsp;case,&nbsp;we&nbsp;want&nbsp;to&nbsp;increase&nbsp;the&nbsp;default&nbsp;cost&nbsp;for&nbsp;BCRYPT&nbsp;to&nbsp;12.<br />&nbsp;*&nbsp;Note&nbsp;that&nbsp;we&nbsp;also&nbsp;switched&nbsp;to&nbsp;BCRYPT,&nbsp;which&nbsp;will&nbsp;always&nbsp;be&nbsp;60&nbsp;characters.<br />&nbsp;*/<br /></span><span style="color: #0000BB">$options&nbsp;</span><span style="color: #007700">=&nbsp;[<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">'cost'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">12</span><span style="color: #007700">,<br />];<br />echo&nbsp;</span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"rasmuslerdorf"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PASSWORD_BCRYPT</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$options</span><span style="color: #007700">).</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
</pre></div>
    </div>
   </div>
  </p>
  
  <p class="para">
   <div class="example" id="example-848">
    <p><strong>Example #3 <span class="function"><strong>password_hash()</strong></span> example setting salt manually</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/**<br />&nbsp;*&nbsp;Note&nbsp;that&nbsp;the&nbsp;salt&nbsp;here&nbsp;is&nbsp;randomly&nbsp;generated.<br />&nbsp;*&nbsp;Never&nbsp;use&nbsp;a&nbsp;static&nbsp;salt&nbsp;or&nbsp;one&nbsp;that&nbsp;is&nbsp;not&nbsp;randomly&nbsp;generated.<br />&nbsp;*<br />&nbsp;*&nbsp;For&nbsp;the&nbsp;VAST&nbsp;majority&nbsp;of&nbsp;use-cases,&nbsp;let&nbsp;password_hash&nbsp;generate&nbsp;the&nbsp;salt&nbsp;randomly&nbsp;for&nbsp;you<br />&nbsp;*/<br /></span><span style="color: #0000BB">$options&nbsp;</span><span style="color: #007700">=&nbsp;[<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">'cost'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">11</span><span style="color: #007700">,<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">'salt'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">mcrypt_create_iv</span><span style="color: #007700">(</span><span style="color: #0000BB">22</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">MCRYPT_DEV_URANDOM</span><span style="color: #007700">),<br />];<br />echo&nbsp;</span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"rasmuslerdorf"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PASSWORD_BCRYPT</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$options</span><span style="color: #007700">).</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.
</pre></div>
    </div>
   </div>
  </p>
  <p class="para">
   <div class="example" id="example-849">
    <p><strong>Example #4 <span class="function"><strong>password_hash()</strong></span> example finding a good cost</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/**<br />&nbsp;*&nbsp;This&nbsp;code&nbsp;will&nbsp;benchmark&nbsp;your&nbsp;server&nbsp;to&nbsp;determine&nbsp;how&nbsp;high&nbsp;of&nbsp;a&nbsp;cost&nbsp;you&nbsp;can<br />&nbsp;*&nbsp;afford.&nbsp;You&nbsp;want&nbsp;to&nbsp;set&nbsp;the&nbsp;highest&nbsp;cost&nbsp;that&nbsp;you&nbsp;can&nbsp;without&nbsp;slowing&nbsp;down<br />&nbsp;*&nbsp;you&nbsp;server&nbsp;too&nbsp;much.&nbsp;10&nbsp;is&nbsp;a&nbsp;good&nbsp;baseline,&nbsp;and&nbsp;more&nbsp;is&nbsp;good&nbsp;if&nbsp;your&nbsp;servers<br />&nbsp;*&nbsp;are&nbsp;fast&nbsp;enough.<br />&nbsp;*/<br /></span><span style="color: #0000BB">$timeTarget&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">0.2</span><span style="color: #007700">;&nbsp;<br /><br /></span><span style="color: #0000BB">$cost&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">9</span><span style="color: #007700">;<br />do&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$cost</span><span style="color: #007700">++;<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$start&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">microtime</span><span style="color: #007700">(</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"test"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PASSWORD_BCRYPT</span><span style="color: #007700">,&nbsp;[</span><span style="color: #DD0000">"cost"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">$cost</span><span style="color: #007700">]);<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$end&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">microtime</span><span style="color: #007700">(</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br />}&nbsp;while&nbsp;((</span><span style="color: #0000BB">$end&nbsp;</span><span style="color: #007700">-&nbsp;</span><span style="color: #0000BB">$start</span><span style="color: #007700">)&nbsp;&lt;&nbsp;</span><span style="color: #0000BB">$timeTarget</span><span style="color: #007700">);<br /><br />echo&nbsp;</span><span style="color: #DD0000">"Appropriate&nbsp;Cost&nbsp;Found:&nbsp;"&nbsp;</span><span style="color: #007700">.&nbsp;</span><span style="color: #0000BB">$cost&nbsp;</span><span style="color: #007700">.&nbsp;</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
Appropriate Cost Found: 11
</pre></div>
    </div>
   </div>
  </p>
 </div>

 
 <div class="refsect1 notes" id="refsect1-function.password-hash-notes">
  <h3 class="title">注释</h3>
  <div class="caution"><strong class="caution">Caution</strong>
   <p class="para">
    It is strongly recommended that you do not generate your own salt for this function. 
    It will create a secure salt automatically for you if you do not specify one.
   </p>
  </div>
  <blockquote class="note"><p><strong class="note">Note</strong>: 
   <p class="para">
    It is recommended that you should test this function on your servers, and adjust the cost 
    parameter so that execution of the function takes approximately 0.1 to 0.5 seconds. The script 
    in the above example will help you choose a good cost value for your hardware.
   </p>
  </p></blockquote>
  <blockquote class="note"><p><strong class="note">Note</strong>: 
   <span class="simpara">
    Updates to supported algorithms by this function (or changes to the default one) must follow 
    the follwoing rules:
   </span>
   <p class="para">
    <ul class="itemizedlist">
     <li class="listitem">
      <span class="simpara">Any new algorithm must be in core for at least 1 full release of PHP prior to becoming
       default. So if, for example, a new algorithm is added in 5.5.5, it would not be eligible for 
       default until 5.7 (since 5.6 would be the first full release). But if a different algorithm was 
       added in 5.6.0, it would also be eligible for default at 5.7.0.
      </span>
     </li>
     <li class="listitem">
      <span class="simpara">
       The default should only change on a full release (5.6.0, 6.0.0, etc) and not on a revision release. 
       The only exception to this is in an emergency when a critical security flaw is found in the current
       default.
      </span>
     </li>
    </ul>
   </p>
  </p></blockquote>
 </div>


 <div class="refsect1 seealso" id="refsect1-function.password-hash-seealso">
  <h3 class="title">参见</h3>
  <p class="para">
   <ul class="simplelist">
    <li class="member"><span class="function"><a href="function.password-verify.html" class="function" rel="rdfs-seeAlso">password_verify()</a> - Verifies that a password matches a hash</span></li>
    <li class="member"><span class="function"><a href="function.crypt.html" class="function" rel="rdfs-seeAlso">crypt()</a> - 单向字符串散列</span></li>
    <li class="member"><a href="https://github.com/ircmaxell/password_compat" class="link external">&raquo;&nbsp;userland implementation</a></li>
   </ul>
  </p>
 </div>


</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="function.password-get-info.html">password_get_info</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="function.password-needs-rehash.html">password_needs_rehash</a></div>
 <div class="up"><a href="ref.password.html">Password Hashing 函数</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
